Skip to main content

Deployment Security Checklist

A pre-deployment review worksheet for FI security / AppSec teams approving an Aspect before it lands in production. Each item lists what to verify, where to verify it, and the expected outcome.

Audience: FI AppSec lead, FI engineering reviewer, FI compliance owner.

Inputs you'll need:

  • The generated Aspect JavaScript file (e.g. ./aspects/<template-id>.js).
  • The Aspect submission PR in the FI's extension repository.
  • Production CSP headers from the FI's web server.
  • The vendor SDK URL(s) and their published SHA-384 hashes (if applicable).
Q-number references

The (Q##) annotations in section headers map to the JavaScript Aspect Architecture, Security, and Compatibility Questionnaire. The full question text and a coverage matrix per template live in Security Questionnaire (Vendor Response). Use this checklist for the verification workflow; use the questionnaire page when you need the canonical question text or a per-template completed response.

Run the mechanical checks in one command

Most of the grep recipes in this checklist are codified into the Forge CLI's aspect verify command:

Bash
forge aspect verify ./aspects/<template-id>.js --template <template-id> --strict

Strict mode exits non-zero on any required-control failure — drop it into your AppSec / CI pipeline. The command checks the same fingerprints listed below; the manual grep recipes remain available for spot-checks or environments where the CLI isn't installed.

1 · Provenance & Submission Pedigree​

  • The PR was submitted via forge aspect submit, not hand-edited after submission. Where: PR description includes the auto-generated metadata block.
  • The submitter is an authorized partner / FI contributor. Where: GitHub author + CODEOWNERS approval.
  • No ad-hoc changes to the generated snippet. Where: git diff between forge aspect preview --template <id> ... --no-save and the committed file should be empty.
  • CI scans (Trivy, MegaLinter) pass on the FI extension repo PR.

2 · XSS & Output Encoding (Q14, Q23)​

For context-aware templates (welcome-banner, personalized-toast):

  • Snippet contains __cdxValidateSession( (session validator inlined).
  • Snippet contains __cdxEsc( (HTML escape helper inlined).
  • Snippet does not contain raw dbk.sessionInfo().userFullName interpolation.
Bash
grep -c '__cdxValidateSession\|__cdxEsc' ./aspects/welcome-banner.js   # expect ≥ 2
grep -c 'dbk.sessionInfo().userFullName'   ./aspects/welcome-banner.js  # expect 0

For all templates that accept a --message parameter:

  • Promotional copy is HTML-escaped at template-generation time. Verify by inspecting the PR with a payload like <script>alert(1)</script> — it must appear as &lt;script&gt;alert(1)&lt;/script&gt; in the emitted file.

3 · URL & Protocol Filtering (Q24)​

For modal and card templates (the two with user-controlled --cta-url):

  • Snippet contains __cdxValidateHttpUrl(.
  • No <a href="javascript: or <a href="data: strings appear in the emitted file.
Bash
grep -c '__cdxValidateHttpUrl' ./aspects/modal.js          # expect ≥ 1
grep -c 'href="javascript:'   ./aspects/modal.js           # expect 0
grep -c 'href="data:'         ./aspects/modal.js           # expect 0

4 · CSP Compliance (Q24)​

  • No inline event handlers anywhere in the snippet:

    Bash
    grep -cE 'onclick="|onerror="|onload="|onmouseover="' ./aspects/<file>.js   # expect 0

  • If the FI's production CSP is style-src 'nonce-<value>' (no 'unsafe-inline'), the Aspect was submitted with --csp-nonce matching the per-request nonce contract:

    Bash
    grep -c "style.setAttribute('nonce'," ./aspects/<file>.js   # expect ≥ 1

  • Test under production CSP. Enable the production CSP headers in a staging environment and verify the Aspect renders without console violations.

5 · Subresource Integrity (Q11, vendor-loader templates only)​

For vendor-script-loader, vendor-script-with-config, tag-manager, vendor-sdk-personalized, mobile-vendor-chat-jsbridge:

  • If the vendor publishes a stable release URL: snippet contains s.integrity = '...'.

  • The integrity hash matches the vendor's published SHA-256 / SHA-384 / SHA-512 digest:

    Bash
    curl -s https://cdn.your-vendor.com/sdk.js \
      | openssl dgst -sha384 -binary \
      | openssl base64 -A
    # → must match the value in the snippet (after the `sha384-` prefix)

  • If vendor-script-with-config is used: CSS hash separately verified via --css-integrity.

  • If SRI is not used: a documented justification in the PR (e.g. "vendor publishes daily silent rebuilds; SRI infeasible").

6 · iframe Sandbox & postMessage (Q8, Q18, Q19, Q20 — hidden-iframe-sso only)​

  • Snippet contains iframe.setAttribute('sandbox', '...') with the minimum required tokens. Default is allow-same-origin allow-scripts. If broader, justified in the PR.

  • Trusted-origin allowlist is bounded:

    Bash
    grep -A 1 '__cdxAllowedOrigins' ./aspects/hidden-iframe-sso.js
    # The array must list only FI / IdP origins; no '*' literal

  • Snippet contains __cdxValidateSsoMessage( (schema validation on token payload).

  • Snippet contains bubbles: false and composed: false on the cdx-aspect:sso-token dispatch.

  • Downstream consumer of cdx-aspect:sso-token (the FI-controlled JS that exchanges the token) verifies the signature field cryptographically. The Forge CLI type-checks it but does not validate the HMAC.

7 · Network Resiliency (Q30, Q31, Q33 — oidc-snippet, mobile-vendor-chat-jsbridge)​

  • Snippet contains function __cdxFetch( (timeout + retry wrapper inlined).

  • Timeout values are appropriate for the target environment:

    Bash
    grep -E 'timeoutMs:\s*[0-9]+' ./aspects/oidc-snippet.js

    Default 10 000 ms is fine for most FIs; tighter timeouts (--timeout-ms 5000) are appropriate for performance-sensitive paths; longer timeouts (--timeout-ms 30000) are appropriate for slow staging environments.

  • Retry count is bounded (default 3, max 5).

  • Test the timeout error path. Block the OIDC endpoint at the network layer; the snippet should surface a "Request timed out after Xms" toast within the configured window — no hung promise, no infinite retry.

8 · Observability (Q35)​

For the three templates that bake correlation IDs (oidc-snippet, mobile-vendor-chat-jsbridge, hidden-iframe-sso):

  • Snippet's console.* lines are tagged with [cdx-aspect:<id>]:

    Bash
    grep -cE '\[cdx-aspect:[A-Za-z0-9._-]+\]' ./aspects/<file>.js   # expect ≥ 1

  • If the FI's CI / release pipeline manages deployment IDs: confirm --correlation-id "$RELEASE_ID" was used in the submission so browser logs can be correlated with releases.

  • Test the log path. Trigger a deliberate error (e.g. invalid clientId) and verify the [cdx-aspect:<id>]-prefixed message reaches the FI's browser-log aggregation system.

9 · Operational Readiness​

  • Runbook exists for the most common Aspect failure modes (vendor SDK 4xx, OIDC timeout, SSO token expired).
  • Vendor escalation contact documented in the FI's incident-response wiki.
  • Rollback procedure documented — typically by reverting the FI extension PR and redeploying.
  • SLO defined for Aspect load time (typical: P95 < 500 ms after host-shell first paint).
  • Alert thresholds configured for elevated [cdx-aspect:*] error rates in the FI's browser-log pipeline.

10 · Compliance & Sign-off​

  • AppSec lead review: confirms all controls in this checklist are met or formally waived.
  • Engineering lead review: confirms operational readiness items.
  • Compliance review: confirms vendor security questionnaire on file (if applicable for vendor-loader templates).
ReviewerNameDateSignature
AppSec lead
Engineering lead
Compliance

What's Out of Scope for This Checklist​

These are tracked under future security work and are not automatically verifiable from the generated snippet alone — coordinate with Candescent before deployment if your risk model requires them:

  • Shadow DOM CSS isolation — parent page styles can affect Aspect UI.
  • HMAC signature verification on SSO signature — type-checked only by the CLI; cryptographic verification is the FI's responsibility.
  • Centralized telemetry pipeline — logs land in console.*; no automatic forwarding to a Candescent endpoint.
  • Vendor SDK runtime behavior — vendor-script-loader and friends don't introspect what the vendor does after load; vendor security review is the FI's responsibility.